% Copyright (c) 2009-2019 The University of Manchester
%
% This program is free software: you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program.  If not, see <http://www.gnu.org/licenses/>.

\def\NoteNum{5}
\def\FullTitle{Spinnaker Command Protocol (SCP) Specification}
\def\ShortTitle{SCP Specification}
\def\Date{16 Mar 2016}
\def\Version{2.0.0}
\def\Author{Steve Temple}
\def\Email{steven.temple@manchester.ac.uk}

\input{../appnote.tex}

\section{Introduction}

The SpiNNaker Command Protocol is a data format imposed on the data
field of an SDP packet. It consists of a fixed-length header followed
by a variable sized data field. It is used for low-level interactions
with SpiNNaker systems for program loading and debugging. It is
suggested that it also be used in applications wherever a similar
facility is needed in order to facilitate code re-use. It is
frequently used to carry a command to a SpiNNaker core and then to
convey a response from that command back to the originator.

The following C struct definition describes the layout of SCP data.

\lstset{language=C}
\begin{lstlisting}
typedef struct
{
  ushort cmd_rc;                // Command/Return Code
  ushort seq;                   // Sequence number
  uint arg1;                    // Arg 1
  uint arg2;                    // Arg 2
  uint arg3;                    // Arg 3
  uchar data[SDP_BUF_SIZE];     // User data (256 bytes)
} sdp_cmd_t;
\end{lstlisting}

\image[scale=0.7]{ht}{sdp-scp.pdf}{sdpscp}{}

The 16-bit {\em cmd\_rc} field is a code indicating the command that
is being specified in the case of a packet conveying a command. Where
the packet is a response to a command, the {\em cmd\_rc} field
indicates a return code following execution of the command.

The 16-bit {\em seq} field may be used for error checking to detect
lost packets and to allow for a retry mechanism. If the field is not
being used it should be set to zero.

The fields {\em arg1}, {\em arg2} and {\em arg3} are provided to allow
32-bit arguments or return values to be transported while the {\em
data} field allows arbitrary data structures to be conveyed. At
present, this field is limited to 256 bytes.

In common with the rest of SpiNNaker, data in the header is stored in
Little Endian Format.

Where not all of the {\em arg1-3} fields are used, it is acceptable, for
reasons of efficiency, to start the data field 'early' (ie to occupy
space unused by {\em arg1-3}) but the {\em cmd\_rc} and {\em seq}
fields must always be present.

\section{Kernel Commands}

SpiNNaker is controlled initially by commands sent from a host system
using SCP. Kernel software running on every active core in the system
accepts and acts upon these commands which are typically used to
download application programs and perform other low-level
functions. At present, the kernel software is {\em SC\&MP} on Monitor
Processors and {\em SARK} on Application processors. {\em SARK}
responds to a small set of commands while {\em SC\&MP} responds to a
larger set. A command is directed to a particular core by means of the
addressing field in the SDP header of the SDP packet which carries the
command. The 3-bit {\em dest\_port} field in the SDP header must be
set to zero so that the command is interpreted by {\em SC\&MP} or {\em
SARK}.

When a core receives one of the kernel commands it attempts to carry
out the requested command and then send back a response packet. The
response may carry some data or it may merely carry a return code,
indicating success or failure of the command. The {\em seq} field from
the incoming packet is copied in the reply so that the sender of
commands can detect packet loss. The packet is returned by swapping
over the {\em Srce} and {\em Dest} fields in the SDP header. If an
error is detected in the processing of the command, a response packet
is sent with an appropriate error code in the {\em cmd\_rc} field. The
kernel checks all of the arguments in the command packet for validity
and may also detect errors during the execution of the command. The three
commands which are currently implemented by all cores are documented
below.

\subsection{Version Command ({\em CMD\_VER})}

The Version command is a request for the core to return some
information about itself and the kernel which is running there. There
are two variants of this command, depending on the version number of
the software tools which are running.  The command and response
packets are shown in the diagram below.

The command packet contains only the command {\em CMD\_VER} (0) in the
{\em cmd\_rc} field and a sequence number in the {\em seq} field. The
other fields are unused and may be omitted from the SDP packet if
desired.

\image[scale=0.67]{ht}{cmd-ver.pdf}{cmdver}{}

The response packet contains several pieces of information packed into
the {\em arg1-3} fields and one or two NULL-terminated text strings in
the data field. {\em arg1} contains the point-to-point address of the
node (if set) in the top 16 bits. It contains the physical CPU number
of the core in bits 15:8 and the virtual CPU number in bits 7:0. {\em
arg2} contains the version number of the kernel software running on
the core in the upper 16 bits and the size of the SCP data buffer in
the lower 16 bits.  The buffer size is the number of bytes that can be
carried in the data portion of a packet carrying SCP. An SDP packet
can hold this number plus 16 (the size of the SCP header).

In versions of the software tools prior to release 2.0.0 the version
number is the major number multiplied by 100 plus the minor number (eg
version 1.29 is represented as 129). In versions from 2.0.0 onwards
the version number is 65535 and an extended version number of the
form ``major.minor.patch'' is present as an ASCII string in the data
field (see diagram)

{\em arg3} contains the build date of the kernel software as a Unix
time (ie seconds since 1970) or zero if this value is not set. The
{\em data} field contains a NULL-terminated ASCII ID string which
consists of two fields separated by a ``/''. The first field is the
name of the kernel (eg {\em SC\&MP} or {\em SARK}) and the second
field is the name of the hardware platform, currently {\em
SpiNNaker}. In versions of the tools from 2.0.0 onwards, a second
(version) string is present which is also NULL-terminated and located
directly after the ID string.

\subsection{Read Command ({\em CMD\_READ})}

The Read command is implemented by all cores. It is used to request
the core to read memory from its address space and return the data
which was read. Up to 256 bytes may be requested in current kernels
(the size may be obtained via the {\em CMD\_VER} command). The core
can be asked to read the memory either as bytes, halfwords (16 bits)
or words (32 bits). For halfwords and words, the size should be a
multiple of 2 or 4 respectively. The command and response packets are
shown in the diagram below.

\image[scale=0.67]{ht}{cmd-read.pdf}{cmdread}{}

In the request, {\em arg1} is the address of the beginning of the read
data. It should be correctly aligned for the data type which is being
specified. {\em arg2} is the number of bytes to be read and {\em arg3}
specifies whether bytes, halfwords or words are being read. Note that
in the response packet, the data immediately follows the {\em cmd\_rc}
and {\em seq} fields as there is no use for the {\em arg1-3} fields in
this case.

\subsection{Write Command ({\em CMD\_WRITE})}

The Write command is implemented by all cores. It is used to request
that a core writes some data to its address space. The parameters are
similar to the Read command in that up to 256 bytes may be written as
either bytes, halfwords or words. The command packet also carries the
data to be written and the response packet carries no data other than
the return code and sequence number. The command and response packets
are shown in the diagram below.

\image[scale=0.67]{ht}{cmd-write.pdf}{cmdwrite}{}

The write command is used extensively to download code and data to
SpiNNaker cores prior to application execution.

\rule{\linewidth}{1pt}

\subsection{\itshape Change log:}

\begin{itemize}
\item {\itshape 1.00 - 28nov11- ST} - initial release - comments to
  {\itshape \Email}
\item {\itshape 2.0.0 - 16mar16 - ST} - update for 2.0.0 tools release.
Amended VER, removed RUN and APLX commands.
\end{itemize}

\end{document}
